<% component = metadata.transforms.lua %>

<%= component_header(component) %>

## Config File

<%= component_config_example(component) %>

## Options

<%= options_table(component.options.to_h.values.sort) %>

## Examples

{% tabs %}
{% tab title="Add fields" %}
Add a field to an event. Supply this as a the `source` value:

```lua
# Add root level field
event["new_field"] = "new value"

# Add nested field
event["parent.child"] = "nested value"
```

{% endtab %}
{% tab title="Remove fields" %}
Remove a field from an event. Supply this as a the `source` value:

```lua
# Remove root level field
event["field"] = nil

# Remove nested field
event["parent.child"] = nil
```

{% endtab %}
{% tab title="Drop event" %}
Drop an event entirely. Supply this as a the `source` value:

```lua
# Drop event entirely
event = nil
```

{% endtab %}
{% endtabs %}

## How It Works [[sort]]

<%= component_sections(component) %>

### Dropping Events

To drop events, simply set the `event` variable to `nil`. For example:

```lua
if event["message"].match(str, "debug") then
  event = nil
end
```

### Global Variables

When evaluating the provided `source`, Vector will provide a single global
variable representing the event:

| Name    |           Type           | Description                                                                                                                                                                       |
|:--------|:------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `event` | [`table`][url.lua_table] | The current [`log` event]. Depending on prior processing the structure of your event will vary. Generally though, it will follow the [default event schema][docs.default_schema]. |

Note, a Lua `table` is an associative array. You can read more about
[Lua types][url.lua_types] in the [Lua docs][url.lua_docs].

### Nested Fields

As described in the [Data Model document][docs.data_model], Vector flatten
events, representing nested field with a `.` delimiter. Therefore, adding,
accessing, or removing nested fields is as simple as added a `.` in your key
name:

```lua
# Add nested field
event["parent.child"] = "nested value"

# Remove nested field
event["parent.child"] = nil
```

### Search Directories

Vector provides a `search_dirs` option that allows you to specify absolute
paths that will searched when using the [Lua `require`
function][url.lua_require].

## Troubleshooting

<%= component_troubleshooting(component) %>

## Resources

<%= component_resources(component) %>